Git

Introduction

At this point in time we have most of our key development tools (package manager, text editor and terminal) setup and ready. Before we can get started with writing code, we need to setup and understand how to use github.The key benefits that we aim to derive from github are:
- Backing up & sharing code (across devices and with others)
- Version control (back tracking and reusing older and different versions)

Two useful resources from which we can get a runthrough of how to use git are:
- git & github tutorial for beginners
- comprehensive guide on git

We don't intend to setup any GUI for github. Instead we will only be operating in the terminal (command line) and on the github website. We quickly note that there are alternatives to github, that allow us to use the git version control system. However, github is the most commonly used, and we will restrict ourselves to the use of github here.

Create a Github Account

Go to github and sign up, following the instructions on the website.

Install Git

A version of git would have already been installed on the system when we installed xcode, as a part of setting up package managers. However, this is likely the apple version of git, and not the official distribution that we want.
We check on this by running " git --version" in the terminal. If the version is something like git version x.xx.x (Apple Git-xxx), we need to install through git
We then install and update our git version by:
- Updating homebrew
- Running "brew install git" in the terminal
- Running "brew upgrade git" in the terminal
- Running "export PATH=/usr/local/bin:$PATH" in the terminal, in order to switch to the homebrew version of git

We can then check if the version has changed by checking the git version once again.

git --version
brew update
brew install git
brew upgrade git
export PATH=/usr/local/bin:$PATH
git --version

Overview

Before going further, we'll take a look at how git works and should be used.
- Each project is contained in one repository or 'repo'. All of the files relevant for that project will be restricted to just this repo.
- Within the repo we have multiple branches, each representing different versions of the code, at varying levels of completeness.
- One primary branch, usually called the 'master' branch should contain the latest version on stable, usable code.
- Each other branch is created as a copy of the master branch (at time of creation). Edits are made to any given branch, and only when we are confident that the edits work well, and are stable, do we merge those changes with the master branch.
- In order to make changes within a branch, we have a 2 step process of staging and commiting:
  - Once changes have been made to files, we use a "git add" command to move these changes to "staging", which is an intermediatte storage location.
  - Once we have changed and moved all of the required files to staging, we can "commit" these changes. This makes all of the edits to the specific branch, and allows us to attach a message, to keep track of this as one unit of change or one complete step in the development process.
- After one or any number of commits made to a branch, we can "push" these changes to the master branch.
- Once changes have been pushed to the master branch, we "pull" and "merge" these changes into the master branch. This essentially means that we accept the changes into the master branch, and in case of any changes conflicating with other changes from other branches, we resolve them.
- Finally, at any stage we can pull master, or any other branch to any device we're working on. This ensures that code stays up to date on all collaborator's devices.

Configuration

We configure git, which we have installed on the laptop with the right user. This will reflect on any git edits in the form of the user name from which the edits are coming.
git configuration guide
In the terminal we run:

git config --global user.name "your Name Here"
git config --global user.email "emailID@emailDomain.com"
git credential-osxkeychain

As long as we get the response "Usage: git credential-osxkeychain <get|store|erase>", we can use the HTTPS method of cloning repositories. If not, check the above link for how to install osxkeychain.

Create Repos

On the github webiste (logged in), click on the dropdown near the '+' icon in the top right corner. Click on "New repository":
- Enter a name for the repository.
- Provide a concise, but clear description.
- Select private, unless the aim is to share the code and make it visible to all.
- Generally add a Readme file and a .gitignore file (selecting the predominant language).
- Click "Create repository".

Clone Repos

Guide to clone a repository :
- On the repository's page on github, click on the dropdown on the green "Code" button with a download symbol.
- Copy the URL in the HTTPS tab.
- In the terminal run "git clone <copied url>".

OR

- In visual studio code.
- ⌘ + Shift + P - command palette.
- Search for "clone" and selct the "Git: Clone" option.
- Paste the url of the repository to be clone.
- Select the destination to clone repository into.

Create Branches

Creating

- To create a new branch, with a base as the current branch, use the command "git checkout -b <new branch name>" in the terminal. This should ideally be done only from the master or primary branch, so that it is easy to maintain the repo. Make sure that the local repository's master branch is up to date, before this operation is done.

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Branch" can be selected.
- Select "Create Branch From…" and enter the name of the new branch.
- Then select the commit from which the branch will be made. (Usually select the most recent commit to master)

Listing

- To view all of the branches present, run "git branch" in the terminal. The list of branches will be printed, with an asterisk against the active branch.

OR

- In VS Code, within the source control tab, the branches sub tab, has this information and more present.

Switching

- To switch branches present, run "git checkout <branch to move to>" in the terminal. This should only be done when there are no unstaged or staged edits, or commits which haven't yet been pushed.

OR

- In VS Code, within the source control tab, the options button has a dropdown, from which "Checkout to…" should be selected.
- And then the branch to move to should be selected.

Deleting

- To delete a branch from the local repository, run "git branch -d <branch>". OR "git branch -D <branch>" to force delete unmerged branches.
- To delete a branch from the remote repository, run "git push origin --delete <branch>".
- Make sure that there are no open pull requests associated with the branch being deleted.

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Branch" can be selected.
- Select "Delete Branch" and select the name of the branch to delete.

Create & Edit Files

In VS Code, within the working directory / local repository, files can be created and edited using the text editor interface as usual. At any point in time VS Code will show the status of each file (against file name) as follows:
A - Added (This is a new file that has been added to the repository)
M - Modified (An existing file has been changed)
D - Deleted (a file has been deleted)
U - Untracked (The file is new or has been changed but has not been added to the repository yet)
C - Conflict (There is a conflict in the file)
R - Renamed (The file has been renamed)
S - Submodule (In repository exists another subrepository)

Status, Log, Show & Diff

git status

Files which have been added to staging and are ready to commit

git log

Commit IDs along with their time, author etc

git show <commit ID>

Details of what was changed in that commit

git diff

Specific lines that have been added/removed/edited, line by line

OR

Using VS Code, each of these changes can be seen inline (because of GitLens extension):
- In the bottom left corner of the editor, the branch name is visible.
- Line by line edit history can be seen inline as well as at the bottom of the editor.
- Within source control tab, the changes files can be seen, as can staged changes.
- The commits sub tab, within the source control tab shows each commit.

Stage, Commit, Head Reset & Ammend

Stage

- To add files to staging, use the command "git add <file name 1> … <file name n>" in the terminal. OR "git add *" to add all modified files to staging. Make sure to only add the files which are part of the project, and not system files (to be added in the ignore file).

OR

- In VS Code, within the source control tab, each of the files that have been changed are visible.
- Select "+" against any file to stage or against all changed files, to stage.

Commit

- To commit the files which have been staged, it is recommended that you first use git status to view the files which will get commited.
- Then run "git commit -m "<message to go with commit>"".

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Commit" can be selected.
- Select "Commit Staged" option and type in the message to commit with.

Reset

- To reset the head (active commit) to a previous commit we can run "git reset --hard <commit id>" or "git reset --soft HEAD~" to reset HEAD by just 1 commit.

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Commit" can be selected.
- Select "Undo Last Commit" option and repeat as many times as needed.

Ammend

- To change only the commit message from the last commit, we can run "git commit --ammend -m "edited message"".
- To change the contents of the required files, we must git add them first, and then either run the above command, or, if we don't want to change the commit message, we run "git commit --ammend --no-edit".
- In both these cases, the previous commit is replaced with this one.

OR

- In VS Code, first stage the required files and enter a message in the source control tab message box, if it needs to be edited.
- Within the source control tab, the options button, has a dropdown, from which "Commit" can be selected.
- Select "Commit Staged (Ammend)" option.

Tag

Tags are a convenient way to name commits so that they are easier to follow. The following terminal commands can be used to apply, list and delete tags:
- "git tag -a <tag name>" tags the commit where the HEAD is currently present.
- "git tag -l" lists all tags.
- "git tag -d <tag name>" deletes the specified tag.

OR

In VS Code, within the source control tab, the options button, has a dropdown, from which tagging operations are possible.

Push

- Once the required changes have been committed to the active branch, we can push the changes to master of the remote repository by running "git push origin master".

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Push" should be selected.
- The first time that this is done, VS Code will inform us that there is no upstream branch, and ask if we should create one, to which we respond "Yes".

Pull & Merge within VS Code

- Within the source control tab's 'branches' sub tab we can switch to the master branch.
- In VS Code, within the source control tab, the options button, has a dropdown, from which "Branch" should be selected.
- "Merge Branch" and the branch within which changes were made should be selected.

Pull & Merge on Github

- On the github site, we will receive a notification that the new branch has recent pushes. We should select the button that says "Compare & pull requests".
- Then we select "Create pull request" (on the github site).
- Then we select "Merge pull request" (on the github site). Sometimes we may have to handle conflicts and only then merge. Then we select "Confirm merge".
- Now the new branch is visible on the github site, and the master branch is also updated.

Pull

- To update the local repository from the remote repository we run "git pull", provided that the active branch is the correct one. Otherwise we may have to specify "git pull <repository> <branch name>".

OR

- In VS Code, within the source control tab, the options button, has a dropdown, from which "Pull" should be selected.

Ignore

The .gitignore file can and should be used to prevent files which are on the laptop (system specific) from getting uploaded to the github repo. To use this, we mention:
- Exact file names
- *.<file extensions>
- <folder names>/

Which are not to be included, within the .gitignore file. While staging and commiting, these files will then no longer show up, and are easily ignored.

Forking

When we clone someone else's repository, github automatically "forks" it. This means that a version of it is created in our list of repositories. From this point onwards, we will not be able to make any edits to the original repo, which we have forked from. Only our, forked repo will be edited by any of our committed and pushed changes.

All Documentation

There is a wide range of additional git functions which are useful in other cases. The github docs can always be refered to for any further queries, outside of the above listed most common activity.
github docs
General google searches, as always are useful in this context.
However, using VS Code and the GitLens extension is significantly easier and smoother than using git via terminal. That after all is why we put the effort into setting up VS Code along with power packed extensions.